home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / lisp / elk-2_0.lha / elk-2.0 / doc / xlib / xlib.ms < prev    next >
Text File  |  1992-07-19  |  57KB  |  1,754 lines
  1. .so ../tmac/tmac.scheme
  2. .RP
  3. .TL
  4. Elk/Xlib Reference Manual
  5. .AU
  6. Oliver Laumann
  7. .
  8. .Ch Introduction
  9. .PP
  10. This document provides a list of the functions, special forms, and variables
  11. exported by the Elk Scheme/Xlib integration.
  12. Most of the functions are directly equivalent to a function of the
  13. Xlib C library, so that the description need not be repeated.
  14. In such cases, only the name of the corresponding Xlib function is
  15. mentioned.
  16. Thus, you should have the \f2Xlib \- C Language X Interface\fP
  17. manual within reach when using this reference manual.
  18. .PP
  19. The functions listed in this document can be loaded by evaluating
  20. the expression
  21. .DS
  22. .ft 5
  23. (require 'xlib).
  24. .ft
  25. .DE
  26. .Ix xlib
  27. in the interpreter's top level or in a Scheme program.
  28. .PP
  29. The types of arguments of the procedures listed below are not described
  30. when they are obvious from the context or from the name.
  31. For instance, an argument named \f2window\fP is always of type \f2window\fP,
  32. an argument named \f2atom\fP is an object of type \f2atom\fP, etc.
  33. Arguments the names of which end in ``?'' are always of type \f2boolean\fP.
  34. .PP
  35. If a function returns several items of the same type (for instance,
  36. a list of windows), the return value is a vector of objects of this type.
  37. If a function returns a collection of items of different types or
  38. of different semantics, the return value is a list of objects
  39. (or a pair).
  40. In this case, \f2multiple-value-bind\fP
  41. .Ix multiple-value-bind
  42. can be used to bind variables to the return values.
  43. .PP
  44. In the following, each description of a procedure, special form, or
  45. variable lists the kind of object in boldface.
  46. Here, \f3procedure\fP denotes either a primitive procedure or a
  47. compound procedure, \f3syntax\fP denotes a special form or a macro,
  48. and \f3variable\fP denotes a global variable that has some initial
  49. value and can be re-assigned a new value by the user (by means
  50. of \f2set!\fP or \f2fluid-let\fP).
  51. .
  52. .Ch Display Functions
  53. .
  54. .Pr display? x
  55. Returns #t iff \f2x\fP is an object of type \f2display\fP.
  56. .
  57. .Pr open-display . name-of-display
  58. See \f2XOpenDisplay\fP.
  59. \f2name-of-display\fP is a string or a symbol.
  60. If no name is specified, a NULL name will be passed to \f2XOpenDisplay\fP.
  61. .
  62. .Pr close-display display
  63. See \f2XCloseDisplay\fP.
  64. Finalizes all objects associated with the display, then closes
  65. the display.
  66. .
  67. .Pr display-default-root-window display
  68. .Up
  69. .Pr display-root-window display
  70. See \f2XDefaultRootWindow\fP.
  71. .
  72. .Pr display-default-colormap display
  73. .Up
  74. .Pr display-colormap display
  75. See \f2XDefaultColormap\fP.
  76. Returns the default colormap of the display's default screen.
  77. .
  78. .Pr display-default-gcontext display
  79. See \f2XDefaultGC\fP.
  80. Returns the default graphics context of the display's default screen.
  81. .
  82. .Pr display-default-depth display
  83. See \f2XDefaultDepth\fP.
  84. Returns the default depth of the display's default screen.
  85. .
  86. .Pr display-default-screen-number display
  87. See \f2XDefaultScreen\fP.
  88. Returns an integer.
  89. .
  90. .Pr display-cells display screen-number
  91. See \f2XDisplayCells\fP.
  92. Returns an integer.
  93. .
  94. .Pr display-planes display screen-number
  95. See \f2XDisplayPlanes\fP.
  96. Returns an integer.
  97. .
  98. .Pr display-string display
  99. See \f2XDisplayString\fP.
  100. Returns a string.
  101. .
  102. .Pr display-vendor display
  103. See \f2XServerVendor\fP, \f2XVendorRelease\fP.
  104. Returns a pair; the car is a string (the vendor identification),
  105. and the cdr is an integer (the vendor release number).
  106. .
  107. .Pr display-protocol-version display
  108. See \f2XProtocolVersion\fP, \f2XProtocolRevision\fP.
  109. Returns a pair of integers (the X protocol's major and minor version numbers).
  110. .
  111. .Pr display-screen-count display
  112. See \f2XScreenCount\fP.
  113. Returns an integer.
  114. .
  115. .Pr display-image-byte-order display
  116. See \f2XImageByteOrder\fP.
  117. Returns a symbol (\f5lsb-first\fP or \f5msb-first\fP).
  118. .
  119. .Pr display-bitmap-unit display
  120. See \f2XBitmapUnit\fP.
  121. Returns an integer.
  122. .
  123. .Pr display-bitmap-bit-order display
  124. See \f2XBitmapBitOrder\fP.
  125. Returns a symbol (\f5lsb-first\fP or \f5msb-first\fP).
  126. .
  127. .Pr display-bitmap-pad display
  128. See \f2XBitmapPad\fP.
  129. Returns an integer.
  130. .
  131. .Pr display-width display
  132. .Up
  133. .Pr display-height display
  134. See \f2XDisplayWidth\fP, \f2XDisplayHeight\fP.
  135. Returns the width/height of the display's default screen.
  136. .
  137. .Pr display-width-mm display
  138. .Up
  139. .Pr display-height-mm display
  140. See \f2XDisplayWidthMM\fP, \f2XDisplayHeightMM\fP.
  141. Returns the width/height of the display's default screen in millimeters.
  142. .
  143. .Pr display-motion-buffer-size display
  144. See \f2XDisplayMotionBufferSize\fP.
  145. Returns an integer.
  146. .
  147. .Pr display-flush-output display
  148. See \f2XFlush\fP.
  149. .
  150. .Pr display-wait-output display discard-events?
  151. See \f2XSync\fP.
  152. .
  153. .Pr no-op display
  154. See \f2XNoOp\fP.
  155. .
  156. .Pr list-depths display screen-number
  157. See \f2XListDepths\fP.
  158. Returns a vector of integers.
  159. .
  160. .Pr list-pixmap-formats display
  161. See \f2XListPixmapFormats\fP.
  162. Returns a vector of lists of three integers (depth, bits per pixel,
  163. and scanline pad).
  164. .
  165. .Pr set-after-function! display procedure
  166. See \f2XSetAfterFunction\fP.
  167. Returns the old after function.
  168. If \f2procedure\fP is #f, the current after function is disassociated
  169. from the display.
  170. .
  171. .Pr after-function display
  172. Returns the after function currently associated with the given
  173. display (#f if there is none).
  174. .
  175. .Pr synchronize display
  176. Sets the display's after function to \f2display-wait-output\fP.
  177. .
  178. .Ch Window Functions
  179. .
  180. .Pr window? x
  181. Returns #t iff \f2x\fP is an object of type \f2window\fP.
  182. .
  183. .Pr drawable? x
  184. Returns #t iff \f2x\fP is a ``drawable'' (window or pixmap).
  185. .
  186. .Pr window-display window
  187. Returns the display associated with the window.
  188. .
  189. .Pr window-unique-id window
  190. Returns a small integer uniquely identifying the given window.
  191. .
  192. .Pr create-window . args
  193. See \f2XCreateWindow\fP.
  194. This function is used to create a new window.
  195. .LP
  196. The number of arguments must be even.
  197. The 1st, 3rd, etc. argument is the name (a symbol) of an attribute
  198. to be set when the window is created, the 2nd, 4th, etc. argument
  199. is the corresponding value.
  200. The attributes can be specified in any order.
  201. .LP
  202. Attributes are \f2x\fP, \f2y\fP, \f2width\fP, \f2height\fP,
  203. \f2border\fP (each of which has an integer value), \f2parent\fP
  204. (the parent window), and all attributes that can be set by means
  205. of the \f5set-window-\fP\f2attribute\fP\f5!\fP functions below
  206. except \f2sibling\fP and \f2stack-mode\fP.
  207. The attributes \f2parent\fP, \f2width\fP, and \f2height\fP are
  208. mandatory.
  209. The default for \f2x\fP and \f2y\fP is 0, the default for
  210. \f2border\fP is 2.
  211. .
  212. .Pr set-window-x! window value
  213. .Up
  214. .Pr set-window-y! window value
  215. .Up
  216. .Pr set-window-width! window value
  217. .Up
  218. .Pr set-window-height! window value
  219. .Up
  220. .Pr set-window-border-width! window value
  221. .Up
  222. .Pr set-window-sibling! window value
  223. .Up
  224. .Pr set-window-stack-mode! window value
  225. .Up
  226. .Pr set-window-background-pixmap! window value
  227. .Up
  228. .Pr set-window-background-pixel! window value
  229. .Up
  230. .Pr set-window-border-pixmap! window value
  231. .Up
  232. .Pr set-window-border-pixel! window value
  233. .Up
  234. .Pr set-window-bit-gravity! window value
  235. .Up
  236. .Pr set-window-gravity! window value
  237. .Up
  238. .Pr set-window-backing-store! window value
  239. .Up
  240. .Pr set-window-backing-planes! window value
  241. .Up
  242. .Pr set-window-backing-pixel! window value
  243. .Up
  244. .Pr set-window-save-under! window value
  245. .Up
  246. .Pr set-window-event-mask! window value
  247. .Up
  248. .Pr set-window-do-not-propagate-mask! window value
  249. .Up
  250. .Pr set-window-override-redirect! window value
  251. .Up
  252. .Pr set-window-colormap! window value
  253. .Up
  254. .Pr set-window-cursor! window value
  255. See \f2XConfigureWindow\fP, \f2XChangeWindowAttributes\fP.
  256. Set the sibling window, stacking mode, background pixmap, background
  257. pixel, border pixel, cursor, and other attributes (see
  258. the \f5window-\fP functions below) of the specified window.
  259. .LP
  260. The stacking mode is a symbol (\f5above\fP, \f5below\fP, \f5top-if\fP,
  261. \f5bottom-if\fP, \f5opposite\fP).
  262. The \f2value\fP argument to \f2set-window-sibling!\fP must be a window,
  263. \f2set-window-background-pixmap!\fP expects a pixmap,
  264. \f2set-window-background-pixel!\fP and \f2set-window-border-pixel!\fP
  265. expect a pixel, and \f2set-window-cursor!\fP expects a cursor argument.
  266. For the types of the \f2value\fP argument of the other functions
  267. see the return values of the \f2window-\fP functions below.
  268. .
  269. .Pr window-x window
  270. .Up
  271. .Pr window-y window
  272. .Up
  273. .Pr window-width window
  274. .Up
  275. .Pr window-height window
  276. .Up
  277. .Pr window-border-width window
  278. .Up
  279. .Pr window-depth window
  280. .Up
  281. .Pr window-visual window
  282. .Up
  283. .Pr window-root window
  284. .Up
  285. .Pr window-class window
  286. .Up
  287. .Pr window-bit-gravity window
  288. .Up
  289. .Pr window-gravity window
  290. .Up
  291. .Pr window-backing-store window
  292. .Up
  293. .Pr window-backing-planes window
  294. .Up
  295. .Pr window-backing-pixel window
  296. .Up
  297. .Pr window-save-under window
  298. .Up
  299. .Pr window-colormap window
  300. .Up
  301. .Pr window-map-installed window
  302. .Up
  303. .Pr window-map-state window
  304. .Up
  305. .Pr window-all-event-masks window
  306. .Up
  307. .Pr window-your-event-mask window
  308. .Up
  309. .Pr window-do-not-propagate-mask window
  310. .Up
  311. .Pr window-override-redirect window
  312. .Up
  313. .Pr window-screen window
  314. See \f2XGetWindowAttributes\fP.
  315. Returns the x and y coordinates, width, height, border width,
  316. depth, visual, root window, class, bit gravity, window gravity,
  317. backing store availability, backing planes, backing pixel,
  318. save under availability, colormap, colormap installation information,
  319. map state, global event mask, local event mask, ``do-not-propagate'' mask,
  320. override redirect attribute, and screen of the specified window.
  321. .LP
  322. \f2window-visual\fP and \f2window-screen\fP always return the empty
  323. list in the current release of the software.
  324. \f2window-root\fP returns a window.
  325. \f2window-class\fP returns a symbol (\f5input-output\fP, \f5input-only\fP).
  326. \f2window-bit-gravity\fP returns a symbol (\f5forget\fP, \f5north-west\fP, 
  327. \f5north\fP, \f5north-east\fP, \f5west\fP, \f5center\fP, \f5east\fP, 
  328. \f5south-west\fP, \f5south\fP, \f5south-east\fP, \f5static\fP).
  329. \f2window-gravity\fP returns a symbol (same as \f2window-bit-gravity\fP
  330. with \f5unmap\fP instead of \f5forget\fP).
  331. \f2window-backing-store\fP returns a symbol (\f5not-useful\fP,
  332. \f5when-mapped\fP, \f5always\fP).
  333. \f2window-backing-planes\fP and \f2window-backing-pixel\fP return
  334. a pixel.
  335. \f2window-save-under\fP, \f2window-map-installed\fP and
  336. \f2window-override-redirect\fP return #t or #f.
  337. \f2window-colormap\fP returns a colormap.
  338. \f2window-map-state\fP returns a symbol (\f5unmapped\fP,
  339. \f5unviewable\fP, \f5viewable\fP).
  340. \f2window-all-event-masks\fP, \f2window-your-event-mask\fP, and
  341. \f2window-do-not-propagate-mask\fP return a list of symbols
  342. (event mask names such as \f5enter-window\fP, \f5pointer-motion\fP, etc.).
  343. All other functions return an integer.
  344. .
  345. .Pr drawable-root drawable
  346. .Up
  347. .Pr drawable-x drawable
  348. .Up
  349. .Pr drawable-y drawable
  350. .Up
  351. .Pr drawable-width drawable
  352. .Up
  353. .Pr drawable-height drawable
  354. .Up
  355. .Pr drawable-border-width drawable
  356. .Up
  357. .Pr drawable-depth drawable
  358. See \f2XGetGeometry\fP.
  359. Returns the root window, x and y coordinates, width, height,
  360. border width, and depth of the specified drawable.
  361. \f2drawable-root\fP returns a window, all other functions return
  362. an integer.
  363. .
  364. .Pr map-window window
  365. See \f2XMapWindow\fP.
  366. .
  367. .Pr unmap-window window
  368. See \f2XUnmapWindow\fP.
  369. .
  370. .Pr destroy-window window
  371. See \f2XDestroyWindow\fP.
  372. .
  373. .Pr destroy-subwindows window
  374. See \f2XDestroySubwindows\fP.
  375. .
  376. .Pr map-subwindows window
  377. See \f2XMapSubwindows\fP.
  378. .
  379. .Pr unmap-subwindows window
  380. See \f2XUnmapSubwindows\fP.
  381. .
  382. .Pr circulate-subwindows window direction
  383. See \f2XCirculateSubwindows\fP.
  384. \f2direction\fP is a symbol (\f5raise-lowest\fP or \f5lower-highest\fP).
  385. .
  386. .Pr clear-window window
  387. Performs a \f2clear-area\fP on the entire window.
  388. .
  389. .Pr raise-window window
  390. See \f2XRaiseWindow\fP.
  391. .
  392. .Pr lower-window window
  393. See \f2XLowerWindow\fP.
  394. .
  395. .Pr restack-windows list-of-windows
  396. See \f2XRestackWindows\fP.
  397. .
  398. .Pr query-tree window
  399. See\f2 XQueryTree\fP.
  400. Returns a list of three elements: root window, parent window, and
  401. children (a vector of windows).
  402. . 
  403. .Pr translate-coordinates src-window x y dst-window
  404. See \f2XTranslateCoordinates\fP.
  405. Returns a list of three elements: destination x and y, and child window.
  406. .
  407. .Pr query-pointer window
  408. See \f2XQueryPointer\fP.
  409. Returns a list of eight elements: x and y, a boolean indicating whether
  410. the pointer is on the same screen as the specified window, the root
  411. window, the root window's x and y coordinates, the child window,
  412. and a list of modifier names (see \f2grab-button\fP
  413. .Ix grab-button
  414. below).
  415. .
  416. .Ch Window Property and Selection Functions
  417. .
  418. .Pr atom? x
  419. Returns #t iff \f2x\fP is an object of type \f2atom\fP.
  420. .
  421. .Pr make-atom value
  422. Returns an atom with the given \f2value\fP.
  423. \f2value\fP is an integer.
  424. .
  425. .Pr intern-atom display name
  426. See \f2XInternAtom\fP.
  427. \f2name\fP is a string or a symbol.
  428. The atom is created if it does not yet exist.
  429. .
  430. .Pr find-atom display name
  431. See \f2XInternAtom\fP.
  432. \f2name\fP is a string or a symbol.
  433. If the atom does not exist, the symbol \f5none\fP is returned.
  434. .
  435. .Pr atom-name display atom
  436. See \f2XGetAtomName\fP.
  437. Returns a string.
  438. .
  439. .Pr list-properties window
  440. See \f2XListProperties\fP.
  441. Returns a vector of atoms.
  442. .
  443. .Pr get-property window property request-type offset length delete?
  444. See \f2XGetWindowProperty\fP.
  445. \f2property\fP is an object of type \f2atom\fP.
  446. \f2request-type\fP is an atom or #f in which case \f2AnyPropertyType\fP
  447. will be used.
  448. \f2offset\fP and \f2length\fP are integers.
  449. An error is signaled if \f2XGetWindowProperty\fP fails.
  450. .LP
  451. \f2get-property\fP returns a list of four items: the ``actual type''
  452. (an atom), the format (an integer), the data (if any, the empty list
  453. otherwise), and the number of bytes left (an integer).
  454. .LP
  455. The data returned is either a string (if the format indicates
  456. 8-bit data) or a vector of integers.
  457. .
  458. .Pr change-property window property type format mode data
  459. See \f2XChangeProperty\fP.
  460. \f2property\fP and \f2type\fP are atoms.
  461. \f2format\fP is an integer (8, 16, or 32).
  462. If \f2format\fP is 8 \f2data\fP must be a string, otherwise a vector of
  463. integers of the appropriate size.
  464. An error is signaled if the
  465. value of \f2format\fP is invalid or if \f2data\fP holds an integer
  466. that exceeds the size indicated by \f2format\fP.
  467. \f2mode\fP is a symbol (\f5replace\fP, \f5prepend\fP, or \f5append\fP).
  468. .
  469. .Pr delete-property window property
  470. See \f2XDeleteProperty\fP.
  471. .
  472. .Pr rotate-properties window vector-of-atoms delta
  473. See \f2XRotateWindowProperties\fP.
  474. \f2delta\fP is the amount to rotate (an integer).
  475. .
  476. .Pr set-selection-owner! display selection owner time
  477. See \f2XSetSelectionOwner\fP.
  478. \f2selection\fP is an atom; \f2owner\fP is a window; \f2time\fP is an
  479. integer or the symbol \f5now\fP (for \f2CurrentTime\fP).
  480. .
  481. .Pr selection-owner display selection
  482. See \f2XGetSelectionOwner\fP.
  483. .
  484. .Pr convert-selection selection target property requestor-window time
  485. See \f2XConvertSelection\fP.
  486. \f2selection\fP and \f2target\fP are atoms;
  487. \f2property\fP is an atom or the symbol \f5none\fP. 
  488. .
  489. .Ch Colormap Functions
  490. .
  491. .Pr color? x
  492. Returns #t iff \f2x\fP is an object of type \f2color\fP.
  493. .
  494. .Pr make-color r g b
  495. Returns an object of type \f2color\fP with the specified RGB components.
  496. \f2r\fP, \f2g\fP, and \f2b\fP are reals in the range 0.0 to 1.0.
  497. .
  498. .Pr color-rgb-values color
  499. Returns a list of three elements, the RGB components of the
  500. given color (see \f2make-color\fP
  501. .Ix make-color
  502. above).
  503. .
  504. .Pr query-color colormap pixel
  505. See \f2XQueryColor\fP.
  506. .
  507. .Pr query-colors colormap pixels
  508. See \f2XQueryColors\fP.
  509. \f2pixels\fP is a vector of pixels.
  510. Returns a vector of colors of the same size as \f2pixels\fP.
  511. .
  512. .Pr lookup-color colormap color-name
  513. See \f2XLookupColor\fP.
  514. \f2color-name\fP is a string or a symbol.
  515. Returns a pair of colors.
  516. .
  517. .Pr colormap? x
  518. Returns #t iff \f2x\fP is an object of type \f2colormap\fP.
  519. .
  520. .Pr colormap-display colormap
  521. Returns the display associated with the given colormap.
  522. .
  523. .Pr free-colormap colormap
  524. See \f2XFreeColormap\fP.
  525. .
  526. .Ch Pixel Functions
  527. .
  528. .Pr pixel? x
  529. Returns #t iff \f2x\fP is an object of type \f2pixel\fP.
  530. .
  531. .Pr pixel-value pixel
  532. Returns the value of the pixel as an unsigned integer.
  533. .
  534. .Pr black-pixel display
  535. .Up
  536. .Pr white-pixel display
  537. See \f2XBlackPixel\fP, \f2XWhitePixel\fP.
  538. Returns the black/white pixel of the display's default screen.
  539. .
  540. .Ch Pixmap Functions
  541. .
  542. .Pr pixmap? x
  543. Returns #t iff \f2x\fP is an object of type \f2pixmap\fP.
  544. .
  545. .Pr pixmap-display pixmap
  546. Returns the display associated with the pixmap.
  547. .
  548. .Pr free-pixmap pixmap
  549. See \f2XFreePixmap\fP.
  550. .
  551. .Pr create-pixmap drawable width height depth
  552. See \f2XCreatePixmap\fP.
  553. .
  554. .Pr create-bitmap-from-data window data width height
  555. See \f2XCreateBitmapFromData\fP.
  556. \f2data\fP is a string.
  557. \f5(* width height)\fP must not exceed the number of bits in \f2string\fP.
  558. .
  559. .Pr create-pixmap-from-bitmap-data win data width height foregrnd backgrnd depth
  560. See \f2XCreatePixmapFromBitmapData\fP.
  561. \f2data\fP is a string.
  562. \f5(* width height)\fP must not exceed the number of bits in \f2string\fP.
  563. .
  564. .Pr read-bitmap-file drawable filename
  565. See \f2XReadBitmapFile\fP.
  566. \f2filename\fP is a string or a symbol.
  567. If \f2XReadBitmapFile\fP signals an error, \f2read-bitmap-file\fP
  568. returns a symbol (\f5open-failed\fP, \f5file-invalid\fP, or \f5no-memory\fP).
  569. If it succeeds, \f2read-bitmap-file\fP returns a list of five elements:
  570. the bitmap (an object of type \f2pixmap\fP), the width and height of the
  571. bitmap, and the x and y coordinates of the hotspot.
  572. .
  573. .Pr write-bitmap-file filename pixmap width height x-hot y-hot
  574. See \f2XWriteBitmapFile\fP.
  575. \f2filename\fP is a string or a symbol.
  576. \f2x-hot\fP and \f2y-hot\fP are optional
  577. (\(mi1 is used if they are omitted), but either both or none of them
  578. must be given.
  579. \f2write-bitmap-file\fP returns a symbol (\f5success\fP, \f5open-failed\fP,
  580. \f5file-invalid\fP, or \f5no-memory\fP).
  581. .
  582. .Ch Graphics Context Functions
  583. .
  584. .Pr gcontext? x
  585. Returns #t iff \f2x\fP is an object of type \f2gcontext\fP.
  586. .
  587. .Pr gcontext-display gcontext
  588. Returns the display associated with the given GC.
  589. .
  590. .Pr create-gcontext . args
  591. See \f2XCreateGC\fP.
  592. This function is used to create a new GC.
  593. .LP
  594. The number of arguments must be even.
  595. The 1st, 3rd, etc. argument is the name (a symbol) of an attribute
  596. to be set when the graphics context is created, the 2nd, 4th, etc. argument
  597. is the corresponding value.
  598. The attributes can be specified in any order.
  599. .LP
  600. Attributes are \f2window\fP (mandatory) and all the attributes that can be
  601. set by the \f5set-gcontext-\fP\f2attribute\fP\f5!\fP functions
  602. below.
  603. .
  604. .Pr copy-gcontext gcontext window
  605. See \f2XCopyGC\fP.
  606. Returns a copy of \f2gcontext\fP (associated with the specified window).
  607. .
  608. .Pr free-gcontext gcontext
  609. See \f2XFreeGC\fP.
  610. .
  611. .Pr query-best-size display width height shape
  612. See \f2XQueryBestSize\fP.
  613. \f2shape\fP is a symbol (\f5cursor\fP, \f5tile\fP, or \f5stipple\fP).
  614. Returns a pair of integers (result width and result height).
  615. .
  616. .Pr query-best-cursor display width height
  617. .Up
  618. .Pr query-best-tile display width height
  619. .Up
  620. .Pr query-best-stipple display width height
  621. See \f2XQueryBestSize\fP.
  622. Invokes \f2query-best-size\fP with the given arguments and a shape
  623. of \f5cursor\fP, \f5tile\fP, or \f5stipple\fP, respectively.
  624. .
  625. .Pr gcontext-function gcontext
  626. .Up
  627. .Pr gcontext-plane-mask gcontext
  628. .Up
  629. .Pr gcontext-foreground gcontext
  630. .Up
  631. .Pr gcontext-background gcontext
  632. .Up
  633. .Pr gcontext-line-width gcontext
  634. .Up
  635. .Pr gcontext-line-style gcontext
  636. .Up
  637. .Pr gcontext-cap-style gcontext
  638. .Up
  639. .Pr gcontext-join-style gcontext
  640. .Up
  641. .Pr gcontext-fill-style gcontext
  642. .Up
  643. .Pr gcontext-fill-rule gcontext
  644. .Up
  645. .Pr gcontext-arc-mode gcontext
  646. .Up
  647. .Pr gcontext-tile gcontext
  648. .Up
  649. .Pr gcontext-stipple gcontext
  650. .Up
  651. .Pr gcontext-ts-x gcontext
  652. .Up
  653. .Pr gcontext-ts-y gcontext
  654. .Up
  655. .Pr gcontext-subwindow-mode gcontext
  656. .Up
  657. .Pr gcontext-exposures gcontext
  658. .Up
  659. .Pr gcontext-clip-x gcontext
  660. .Up
  661. .Pr gcontext-clip-y gcontext
  662. .Up
  663. .Pr gcontext-dash-offset gcontext
  664. See \f2XGetGCValues\fP.
  665. Returns the 
  666. logical operation, plane mask, foreground and background pixel
  667. value, line width and style, cap and join style, fill style and rule,
  668. arc mode, tiling and stippling pixmap, tiling x- and y-origin,
  669. subwindow mode, clipping x- and y-origin, and dashed line
  670. information of the specified graphics context.
  671. .LP
  672. \f2gcontext-function\fP returns a symbol
  673. (\f5clear\fP, \f5and\fP, \f5and-reverse\fP, \f5copy\fP, \f5and-inverted\fP,
  674. \f5no-op\fP, \f5xor\fP, \f5or\fP, \f5nor\fP, \f5equiv\fP, \f5invert\fP,
  675. \f5or-reverse\fP, \f5copy-inverted\fP, \f5nand\fP, or \f5set\fP).
  676. \f2gcontext-plane-mask\fP, \f2gcontext-foreground\fP,
  677. and \f2gcontext-background\fP return a pixel.
  678. \f2gcontext-tile\fP and \f2gcontext-stipple\fP return a pixmap.
  679. The line style is a symbol (\f5solid\fP, \f5dash\fP, \f5double-dash\fP);
  680. the cap style is a symbol (\f5not-last\fP, \f5butt\fP, \f5round\fP,
  681. \f5projecting\fP); the join style is a symbol (\f5miter\fP, \f5round\fP,
  682. \f5bevel\fP); the fill style is a symbol (\f5solid\fP, \f5tiled\fP,
  683. \f5stippled\fP, \f5opaque-stippled\fP); the fill rule is a symbol
  684. (\f5even-odd\fP, \f5winding\fP); the arc mode is a symbol (\f5chord\fP,
  685. \f5pie-slice\fP); the subwindow-mode is a symbol
  686. (\f5clip-by-children\fP, \f5include-inferiors\fP).
  687. \f2gcontext-exposures\fP returns a boolean.
  688. All other functions return an integer.
  689. .
  690. .Pr set-gcontext-function! gcontext value
  691. .Up
  692. .Pr set-gcontext-plane-mask! gcontext value
  693. .Up
  694. .Pr set-gcontext-foreground! gcontext value
  695. .Up
  696. .Pr set-gcontext-background! gcontext value
  697. .Up
  698. .Pr set-gcontext-line-width! gcontext value
  699. .Up
  700. .Pr set-gcontext-line-style! gcontext value
  701. .Up
  702. .Pr set-gcontext-cap-style! gcontext value
  703. .Up
  704. .Pr set-gcontext-join-style! gcontext value
  705. .Up
  706. .Pr set-gcontext-fill-style! gcontext value
  707. .Up
  708. .Pr set-gcontext-fill-rule! gcontext value
  709. .Up
  710. .Pr set-gcontext-arc-mode! gcontext value
  711. .Up
  712. .Pr set-gcontext-tile! gcontext value
  713. .Up
  714. .Pr set-gcontext-stipple! gcontext value
  715. .Up
  716. .Pr set-gcontext-ts-x! gcontext value
  717. .Up
  718. .Pr set-gcontext-ts-y! gcontext value
  719. .Up
  720. .Pr set-gcontext-font! gcontext value
  721. .Up
  722. .Pr set-gcontext-subwindow-mode! gcontext value
  723. .Up
  724. .Pr set-gcontext-exposures! gcontext value
  725. .Up
  726. .Pr set-gcontext-clip-x! gcontext value
  727. .Up
  728. .Pr set-gcontext-clip-y! gcontext value
  729. .Up
  730. .Pr set-gcontext-clip-mask! gcontext value
  731. .Up
  732. .Pr set-gcontext-dash-offset! gcontext value
  733. See \f2XChangeGC\fP.
  734. Sets the logical operation, plane mask, foreground and background pixel
  735. value, line width and style, cap and join style, fill style and rule,
  736. arc mode, tiling and stippling pixmap, tiling x- and y-origin, font,
  737. subwindow mode, clipping x- and y-origin, clipping bitmap, and dashed line
  738. information for the specified graphics context.
  739. .LP
  740. The \f2value\fP argument to \f2set-gcontext-font!\fP is a font,
  741. and the \f2value\fP argument to \f2set-gcontext-clip-mask!\fP
  742. is a pixmap.
  743. For the types of the \f2value\fP argument of the other functions
  744. see the return values of the \f2gcontext-\fP functions above.
  745. .
  746. .Pr set-gcontext-clip-rectangles! gcontext x y rectangles ordering
  747. See \f2XSetClipRectangles\fP.
  748. \f2x\fP and \f2y\fP are integers (the coordinates of the clip-mask origin).
  749. \f2rectangles\fP is a vector of lists of four integers (x, y, width,
  750. and height of each rectangle).
  751. \f2ordering\fP is a symbol (\f5unsorted\fP, \f5y-sorted\fP, \f5yx-sorted\fP,
  752. or \f5yx-banded\fP).
  753. .
  754. .Pr set-gcontext-dashlist! gcontext dash-offset dash-list
  755. See \f2XSetDashes\fP.
  756. \f2dash-offset\fP is an integer.
  757. \f2dash-list\fP is a vector of integers between 0 and 255.
  758. .
  759. .Ch Graphics Functions
  760. .
  761. .Pr clear-area window x y width height exposures?
  762. See \f2XClearArea\fP.
  763. .
  764. .Pr copy-area src-drawable gcontext src-x src-y width height dst-drawable "dst-x dst-y"
  765. See \f2XCopyArea\fP.
  766. .
  767. .Pr copy-plane src-drawable gcontext plane src-x src-y width height "dst-drawable dst-x dst-y"
  768. See \f2XCopyPlane\fP.
  769. \f2plane\fP is an integer.
  770. An error is signaled unless exactly one bit is set in \f2plane\fP.
  771. .
  772. .Pr draw-point drawable gcontext x y
  773. See \f2XDrawPoint\fP.
  774. .
  775. .Pr draw-points drawable gcontext vector-of-points relative?
  776. See \f2XDrawPoints\fP.
  777. \f2vector-of-points\fP is a vector of pairs consisting of two integers
  778. (the x and y coordinates).
  779. If \f2relative?\fP is #t, \f2CoordModePrevious\fP
  780. is passed to \f2XDrawPoints\fP, otherwise \f2CoordModeOrigin\fP is used.
  781. .
  782. .Pr draw-line drawable gcontext x1 y1 x2 y2
  783. See \f2XDrawLine\fP.
  784. .
  785. .Pr draw-lines drawable gcontext vector-of-points relative?
  786. See \f2XDrawLines\fP.
  787. See \f2draw-points\fP
  788. .Ix draw-points
  789. above.
  790. .
  791. .Pr draw-segments drawable gcontext vector-of-points
  792. See \f2XDrawSegments\fP.
  793. \f2vector-of-points\fP is a vector of lists of four integers
  794. (x1, y1, x2, and y2).
  795. .
  796. .Pr draw-rectangle drawable gcontext x y width height
  797. See \f2XDrawRectangle\fP.
  798. .
  799. .Pr fill-rectangle drawable gcontext x y width height
  800. See \f2XFillRectangle\fP.
  801. .
  802. .Pr draw-rectangles drawable gcontext vector-of-rectangles
  803. See \f2XDrawRectangles\fP.
  804. \f2vector-of-rectangles\fP is a vector of lists of four integers
  805. (x, y, width, and height of each rectangle).
  806. .
  807. .Pr fill-rectangles drawable gcontext vector-of-rectangles
  808. See \f2XFillRectangles\fP.
  809. See \f2draw-rectangles\fP
  810. .Ix draw-rectangles
  811. above.
  812. .
  813. .Pr draw-arc drawable gcontext x y width height angle1 angle2
  814. See \f2XDrawArc\fP.
  815. .
  816. .Pr fill-arc drawable gcontext x y width height angle1 angle2
  817. See \f2XFillArc\fP.
  818. .
  819. .Pr draw-arcs drawable gcontext vector-of-data
  820. See \f2XDrawArcs\fP.
  821. \f2vector-of-data\fP is a vector of lists of six integers
  822. (x, y, width, height, angle1, and angle2).
  823. .
  824. .Pr fill-arcs drawable gcontext vector-of-data
  825. See \f2XFillArcs\fP.
  826. See \f2draw-arcs\fP
  827. .Ix draw-arcs
  828. above.
  829. .
  830. .Pr fill-polygon drawable gcontext vector-of-points relative? shape
  831. See \f2XFillPolygon\fP.
  832. See \f2draw-points\fP
  833. .Ix draw-points
  834. above.
  835. \f2shape\fP is a symbol (\f5complex\fP, \f5non-convex\fP, or \f5convex\fP).
  836. .
  837. .Ch Font Functions
  838. .
  839. .Pr font? x
  840. Returns #t iff \f2x\fP is an object of type \f2font\fP.
  841. .
  842. .Pr font-display
  843. Returns the display associated with the given font.
  844. .
  845. .Pr open-font display font-name
  846. See \f2XLoadQueryFont\fP.
  847. \f2font-name\fP is a string or a symbol.
  848. .
  849. .Pr close-font font
  850. See \f2XUnloadFont\fP.
  851. .
  852. .Pr font-name font
  853. Returns the name of the specified font (a string) or #f if the name could
  854. not be determined (e.g. when the font has been obtained by a call
  855. to \f2gcontext-font\fP).
  856. .
  857. .Pr gcontext-font gcontext
  858. Calls \f2XQueryFont\fP with the GC obtained by \f2XGContextFromGC\fP.
  859. Only a limited number of functions can be applied to a font
  860. returned by \f2gcontext-font\fP, since it has neither a name nor
  861. a font-ID.
  862. .
  863. .Pr list-font-names display pattern
  864. See \f2XListFonts\fP.
  865. \f2pattern\fP is a string or a symbol.
  866. Returns a vector of font names (strings).
  867. .
  868. .Pr list-fonts display pattern
  869. See \f2XListFontsWithInfo\fP.
  870. \f2pattern\fP is a string or a symbol.
  871. Returns a vector of fonts.
  872. These fonts are ``pseudo fonts'' which do not have a font-ID.
  873. A pseudo font is loaded automatically and turned into a ``real''
  874. font the first time it is passed to a function that makes use
  875. of the font-ID.
  876. .
  877. .Pr font-direction font
  878. .Up
  879. .Pr font-min-byte2 font
  880. .Up
  881. .Pr font-max-byte2 font
  882. .Up
  883. .Pr font-min-byte1 font
  884. .Up
  885. .Pr font-max-byte1 font
  886. .Up
  887. .Pr font-all-chars-exist? font
  888. .Up
  889. .Pr font-default-char font
  890. .Up
  891. .Pr font-ascent font
  892. .Up
  893. .Pr font-descent font
  894. These functions return the font direction as a symbol (\f5left-to-right\fP
  895. or \f5right-to-left\fP), the first and last character (as an integer),
  896. the first and last row (integer), an indication whether all characters
  897. have non-zero size (boolean), the default character (integer), and the
  898. ascent and descent (integer) of the specified font.
  899. .
  900. .Pr char-rbearing font index
  901. .Up
  902. .Pr char-lbearing font index
  903. .Up
  904. .Pr char-width font index
  905. .Up
  906. .Pr char-ascent font index
  907. .Up
  908. .Pr char-descent font index
  909. These functions return the metrics of
  910. the character specified by the integer \f2index\fP of the given font.
  911. Each function returns an integer.
  912. \f2font\fP can be a 1-byte as well as a 2-byte font.
  913. .
  914. .Pr max-char-lbearing font
  915. .Up
  916. .Pr max-char-rbearing font
  917. .Up
  918. .Pr max-char-width font
  919. .Up
  920. .Pr max-char-ascent font
  921. .Up
  922. .Pr max-char-descent font
  923. These functions return the maximum metrics over all characters
  924. in the specified font.
  925. Each function returns an integer.
  926. .
  927. .Pr min-char-lbearing font
  928. .Up
  929. .Pr min-char-rbearing font
  930. .Up
  931. .Pr min-char-width font
  932. .Up
  933. .Pr min-char-ascent font
  934. .Up
  935. .Pr min-char-descent font
  936. These functions return the minimum metrics over all characters
  937. in the specified font.
  938. Each function returns an integer.
  939. .
  940. .Pr font-properties font
  941. Returns a vector of font properties; each element of the vector
  942. is a pair consisting of the property name (an atom) and an
  943. unsigned integer (the value of the property).
  944. .
  945. .Pr font-property font property-name
  946. Returns the value of the specified property associated with the
  947. specified font.
  948. \f2property-name\fP is a string or a symbol.
  949. .
  950. .Pr font-path display
  951. See \f2XGetFontPath\fP.
  952. Returns the current font path as a vector of strings.
  953. .
  954. .Pr set-font-path! display path
  955. See \f2XSetFontPath\fP.
  956. \f2path\fP is a list; each element is a string or a symbol.
  957. .
  958. .Ch Text Metrics and Text Drawing Functions
  959. .
  960. .Pr text-width font text format
  961. See \f2XTextWidth\fP, \f2XTextWidth16\fP.
  962. \f2format\fP indicates whether 8-bit or 16-bit text is used; it is either
  963. the symbol \f51-byte\fP or the symbol \f52-byte\fP.
  964. \f2text\fP is a vector of integers; the integers must not exceed the
  965. size indicated by the format.
  966. .
  967. .Pr extents-lbearing font text format
  968. .Up
  969. .Pr extents-rbearing font text format
  970. .Up
  971. .Pr extents-width font text format
  972. .Up
  973. .Pr extents-ascent font text format
  974. .Up
  975. .Pr extents-descent font text format
  976. See \f2XTextExtents\fP, \f2XTextExtents16\fP.
  977. These functions are used to compute the overall metrics of an 8-bit
  978. or 16-bit character string.
  979. Each function returns an integer.
  980. For the format of \f2text\fP and \f2format\fP see \f2text-width\fP
  981. .Ix text-width
  982. above.
  983. .
  984. .Pr draw-image-text drawable gcontext x y text format
  985. See \f2XDrawImageString\fP, \f2XDrawImageString16\fP.
  986. See \f2text-width\fP
  987. .Ix text-width
  988. above.
  989. .
  990. .Pr draw-poly-text drawable gcontext x y text format
  991. See \f2XDrawText\fP, \f2XDrawText16\fP.
  992. See \f2text-width\fP
  993. .Ix text-width
  994. above.
  995. \f2text\fP is a vector of integers with intermixed objects of type \f2font\fP.
  996. .
  997. .Pr translate-text string
  998. Converts the string into a representation suitable as an argument
  999. to \f2text-width\fP, \f2draw-image-text\fP, or \f2draw-poly-text\fP
  1000. (a vector of integers obtained by applying \f2char\(mi>integer\fP
  1001. to the characters of the string argument).
  1002. .
  1003. .Ch Cursor Functions
  1004. .
  1005. .Pr cursor? x
  1006. Returns #t iff \f2x\fP is an object of type \f2cursor\fP.
  1007. .
  1008. .Pr cursor-display cursor
  1009. Returns the display associated with the given cursor.
  1010. .
  1011. .Pr free-cursor
  1012. See \f2XFreeCursor\fP.
  1013. .
  1014. .Pr create-cursor src mask x y foreground background
  1015. See \f2XCreatePixmapCursor\fP.
  1016. \f2src\fP and \f2mask\fP are pixmaps.
  1017. \f2mask\fP can be the symbol \f5none\fP.
  1018. .
  1019. .Pr create-glyph-cursor src src-char mask mask-char foreground background
  1020. See \f2XCreateGlyphCursor\fP.
  1021. \f2src\fP and \f2mask\fP are fonts.
  1022. \f2mask\fP can be the symbol \f5none\fP.
  1023. The display is obtained from \f2src\fP.
  1024. \f2src-char\fP and \f2mask-char\fP are integers.
  1025. .
  1026. .Pr create-font-cursor display src-char
  1027. See \f2XCreateGlyphCursor\fP.
  1028. Calls \f2create-glyph-cursor\fP with the font named ``cursor'', the
  1029. specified \f2src-char\fP, a \f2mask-char\fP of \f5(1+ src-char)\fP,
  1030. black foreground, and white background.
  1031. .
  1032. .Pr recolor-cursor cursor foreground background
  1033. See \f2XRecolorCursor\fP
  1034. .
  1035. .Pr define-cursor window cursor
  1036. Synonym for \f5(set-window-cursor! window cursor)\fP.
  1037. .
  1038. .Pr undefine-cursor window
  1039. Synonym for \f5(set-window-cursor! window 'none)\fP.
  1040. .
  1041. .Ch Grab Functions
  1042. .
  1043. .Pr grab-pointer window owner? events ptr-sync? kbd-sync? confine-to cursor time
  1044. See \f2XGrabPointer\fP.
  1045. \f2window\fP and \f2confine-to\fP are windows.
  1046. \f2events\fP is a list of symbols (event mask names, such as \f5enter-window\fP,
  1047. \f5pointer-motion\fP, etc.).
  1048. \f2ptr-sync?\fP and \f2kbd-sync?\fP determine whether synchronous
  1049. or asynchronous grab mode is to be used.
  1050. \f2time\fP is an integer or the symbol \f5now\fP (for \f2CurrentTime\fP).
  1051. \f2grab-pointer\fP returns a symbol (\f5success\fP, \f5not-viewable\fP,
  1052. \f5already-grabbed\fP, \f5frozen\fP, or \f5invalid-time\fP).
  1053. .
  1054. .Pr ungrab-pointer display time
  1055. See \f2XUngrabPointer\fP.
  1056. .
  1057. .Pr grab-button win button mod owner? events ptr-sync? kbd-sync? "confine-to cursor"
  1058. See \f2XGrabButton\fP.
  1059. \f2button\fP is a symbol (\f5button1\fP .. \f5button5\fP, or \f5any-button\fP).
  1060. \f5mod\fP (modifiers) is a list of symbols (\f5shift\fP, \f5lock\fP,
  1061. \f5control\fP, \f5mod1\fP .. \f5mod5\fP, \f5button1\fP .. \f5button5\fP,
  1062. or \f5any-modifier\fP).
  1063. For the other arguments see \f2grab-pointer\fP
  1064. .Ix grab-pointer
  1065. above.
  1066. .
  1067. .Pr ungrab-button window button modifiers
  1068. See \f2XUngrabButton\fP.
  1069. See \f2grab-button\fP
  1070. .Ix grab-button
  1071. above.
  1072. .
  1073. .Pr change-active-pointer-grab display events cursor time
  1074. See \f2XChangeActivePointerGrab\fP.
  1075. \f2events\fP is a list of symbols (event mask names, such as \f5enter-window\fP,
  1076. \f5pointer-motion\fP, etc.).
  1077. .
  1078. .Pr grab-keyboard window owner? pointer-sync? keyboard-sync? time
  1079. See \f2XGrabKeyboard\fP.
  1080. For a description of the arguments and the return value see \f2grab-pointer\fP
  1081. .Ix grab-pointer
  1082. above.
  1083. .
  1084. .Pr ungrab-keyboard display time
  1085. See \f2XUngrabKeyboard\fP.
  1086. .
  1087. .Pr grab-key window key modifiers owner? pointer-sync? keyboard-sync?
  1088. See \f2XGrabKey\fP.
  1089. \f2key\fP is a keycode (an integer) or the symbol \f5any\fP.
  1090. For the other arguments see \f2grab-pointer\fP
  1091. .Ix grab-pointer
  1092. above.
  1093. .
  1094. .Pr ungrab-key window key modifiers
  1095. See \f2XUngrabKey\fP.
  1096. See \f2grab-key\fP
  1097. .Ix grab-key
  1098. above.
  1099. .
  1100. .Pr allow-events display mode time
  1101. See \f2XAllowEvents\fP.
  1102. \f2mode\fP is a symbol (\f5async-pointer\fP, \f5sync-pointer\fP,
  1103. \f5replay-pointer\fP, \f5async-keyboard\fP, \f5sync-keyboard\fP,
  1104. \f5replay-keyboard\fP, \f5async-both\fP, or \f5sync-both\fP).
  1105. .
  1106. .Pr grab-server display
  1107. See \f2XGrabServer\fP.
  1108. .
  1109. .Pr ungrab-server display
  1110. See \f2XUngrabServer\fP.
  1111. .
  1112. .Sy with-server-grabbed display . body-forms
  1113. This macro performs a \f2grab-server\fP on the specified display,
  1114. evaluates the \f2body-forms\fP in order, and then ungrabs the server.
  1115. The macro body is guarded by a \f2dynamic-wind\fP to ensure that the
  1116. \f2ungrab-server\fP is performed when a body-form calls a continuation
  1117. created outside the macro, and that it is grabbed again when
  1118. the body is re-entered at a later point in time.
  1119. \f2with-server-grabbed\fP returns the value of the last body-form.
  1120. .
  1121. .Ch Window Manager Functions
  1122. .
  1123. .Pr reparent-window window parent-window x y
  1124. See \f2XReparentWindow\fP.
  1125. .
  1126. .Pr install-colormap colormap
  1127. See \f2XInstallColormap\fP.
  1128. .
  1129. .Pr uninstall-colormap colormap
  1130. See \f2XUninstallColormap\fP.
  1131. .
  1132. .Pr list-installed-colormaps window
  1133. See \f2XListInstalledColormaps\fP.
  1134. Returns a vector of colormaps.
  1135. .
  1136. .Pr set-input-focus display window revert-to time
  1137. See \f2XSetInputFocus\fP.
  1138. \f2window\fP can be the symbol \f5pointer-root\fP.
  1139. \f2revert-to\fP is a symbol (\f5none\fP, \f5pointer-root\fP, or \f5parent\fP).
  1140. \f2time\fP is an integer or the symbol \f5now\fP.
  1141. .
  1142. .Pr input-focus display
  1143. See \f2XGetInputFocus\fP.
  1144. Returns a pair the car of which is a window, and the cdr is a symbol
  1145. (\f5none\fP, \f5pointer-root\fP, or \f5parent\fP).
  1146. .
  1147. .Pr general-warp-pointer display dst-win dst-x dst-y src-win src-x src-y "src-width src-height"
  1148. See \f2XWarpPointer\fP.
  1149. .
  1150. .Pr warp-pointer dst-window dst-x dst-y
  1151. See \f2XWarpPointer\fP.
  1152. Invokes \f2general-warp-pointer\fP with the display associated with the
  1153. \f2dst-window\fP, the \f2dst-window\fP, \f2dst-x\fP, \f2dst-y\fP,
  1154. a \f2src-window\fP of \f5none\fP, and zero source coordinates and dimensions.
  1155. .
  1156. .Pr warp-pointer-relative display x-offset y-offset
  1157. See \f2XWarpPointer\fP.
  1158. Invokes \f2general-warp-pointer\fP with the specified \f2display\fP,
  1159. a \f2dst-window\fP of \f5none\fP, \f2x-offset\fP, \f2y-offset\fP,
  1160. a \f2src-window\fP of \f5none\fP, and zero source coordinates and dimensions.
  1161. .
  1162. .Pr bell display . percent
  1163. See \f2XBell\fP.
  1164. \f2percent\fP is an integer between -100 and 100.
  1165. If \f2percent\fP is omitted, 0 is used.
  1166. .
  1167. .Pr set-access-control display enable?
  1168. See \f2XSetAccessControl\fP.
  1169. .
  1170. .Pr change-save-set window mode
  1171. See \f2XChangeSaveSet\fP.
  1172. \f2mode\fP is a symbol (\f5insert\fP or \f5delete\fP).
  1173. .
  1174. .Pr set-close-down-mode display mode
  1175. See \f2XSetCloseDownMode\fP.
  1176. \f2mode\fP is a symbol (\f5destroy-all\fP, \f5retain-permanent\fP,
  1177. or \f5retain-temporary\fP).
  1178. .
  1179. .Pr get-pointer-mapping display
  1180. See \f2XGetPointerMapping\fP.
  1181. Returns a vector of 256 integers.
  1182. .
  1183. .Pr set-pointer-mapping display mapping
  1184. See \f2XSetPointerMapping\fP.
  1185. \f2mapping\fP is a vector of integers.
  1186. Returns #t if \f2XSetPointerMapping\fP succeeds, #f otherwise.
  1187. .
  1188. .Ch Event Handling Functions
  1189. .
  1190. .Pr event-listen display wait?
  1191. See \f2XPending\fP, \f2XPeekEvent\fP.
  1192. Returns the size of the display's event queue.
  1193. If \f2wait?\fP is true and the event queue is empty, \f2event-listen\fP
  1194. flushes the output buffer and blocks until an event is received from
  1195. the server.
  1196. .
  1197. .Pr get-motion-events window from-time to-time
  1198. See \f2XGetMotionEvents\fP.
  1199. \f2from-time\fP and \f2to-time\fP are integers or the symbol \f5now\fP.
  1200. \f2get-motion-events\fP returns a vector of lists of three elements:
  1201. a time stamp (an integer or the symbol \f5now\fP), and the x and y 
  1202. coordinates (integers).
  1203. .
  1204. .Sy handle-events display discard? peek? . clauses
  1205. See \f2XNextEvent\fP, \f2XPeekEvent\fP, \f2XIfEvent\fP, \f2XPeekIfEvent\fP.
  1206. \f2handle-events\fP is a special form.
  1207. Each \f2clause\fP is of the form \f2(guard function)\fP; \f2guard\fP
  1208. is either an event name (a symbol, e.g. \f5key-press\fP or \f5exposure\fP),
  1209. a list of event names, or the symbol \f5else\fP.
  1210. \f2handle-events\fP gets the next event from the specified display.
  1211. Then the event type is matched against each event name in each guard
  1212. in order.
  1213. When a match occurs, the corresponding function is invoked with
  1214. the name of the event being dispatched (a symbol) and other, event
  1215. specific arguments (see below).
  1216. When no clause matches and an \f5else\fP clause is present, the function
  1217. from this clause is invoked.
  1218. \f2handle-events\fP loops until a function returns a value not
  1219. equal to #f in which case handle-events returns this value.
  1220. .LP
  1221. If \f2discard?\fP is true, unprocessed events (i.\|e. events for which
  1222. no matching clause has been found) are removed from the event queue,
  1223. otherwise they are left in place.
  1224. If \f2peek?\fP is true, processed events are not removed from
  1225. the event queue.
  1226. .LP
  1227. The following list gives all event specific arguments for each
  1228. event type.
  1229. The first argument is always the event type (a symbol).
  1230. .LP
  1231. In the following list, arguments with names of the form
  1232. \f2something-window\fP (or simply \f2window\fP) are always of type
  1233. \f2window\fP;
  1234. arguments with names of the form \f2something-atom\fP (or simply \f2atom\fP)
  1235. are always of type \f2atom\fP.
  1236. \f2time\fP is an integer or the symbol \f5now\fP.
  1237. \f2x\fP, \f2y\fP, \f2width\fP, \f2height\fP, \f2border-width\fP,
  1238. \f2x-root\fP, \f2y-root\fP, \f2count\fP, \f2major-code\fP, \f2minor-code\fP,
  1239. and \f2keycode\fP are integers.
  1240. \f2state\fP is a list of symbols (\f5shift\fP, \f5lock\fP, \f5control\fP,
  1241. \f5mod1\fP .. \f5mod5\fP, \f5button1\fP .. \f5button5\fP).
  1242. \f2button\fP is one of the symbols \f5button1\fP .. \f5button5\fP,
  1243. \f2button-mask\fP is a list of one or more of these symbols.
  1244. \f2cross-mode\fP is a symbol (\f5normal\fP, \f5grab\fP, \f5ungrab\fP).
  1245. \f2place\fP is a symbol (\f5top\fP or \f5bottom\fP).
  1246. .
  1247. .IP "\f3key-press, key-release:\fP"
  1248. .Ix "Event types" key-press
  1249. .Ix "Event types" key-release
  1250. \f2window\fP, \f2root-window\fP, \f2sub-window\fP, \f2time\fP,
  1251. \f2x\fP, \f2y\fP, \f2x-root\fP, \f2y-root\fP, \f2state\fP, \f2keycode\fP,
  1252. \f2same-screen?\fP.
  1253. .
  1254. .IP "\f3button-press, button-release:\fP"
  1255. .Ix "Event types" button-press
  1256. .Ix "Event types" button-release
  1257. \f2window\fP, \f2root-window\fP, \f2sub-window\fP, \f2time\fP,
  1258. \f2x\fP, \f2y\fP, \f2x-root\fP, \f2y-root\fP, \f2state\fP, \f2button\fP,
  1259. \f2same-screen?\fP.
  1260. .
  1261. .IP "\f3motion-notify:\fP"
  1262. .Ix "Event types" motion-notify
  1263. \f2window\fP, \f2root-window\fP, \f2sub-window\fP, \f2time\fP,
  1264. \f2x\fP, \f2y\fP, \f2x-root\fP, \f2y-root\fP, \f2state\fP, \f2is-hint?\fP,
  1265. \f2same-screen?\fP.
  1266. .
  1267. .IP "\f3enter-notify, leave-notify:\fP"
  1268. .Ix "Event types" enter-notify
  1269. .Ix "Event types" leave-notify
  1270. \f2window\fP, \f2root-window\fP, \f2sub-window\fP, \f2time\fP,
  1271. \f2x\fP, \f2y\fP, \f2x-root\fP, \f2y-root\fP, \f2cross-mode\fP,
  1272. \f2cross-detail\fP (one of the symbols \f5ancestor\fP, \f5virtual\fP,
  1273. \f5inferior\fP, \f5nonlinear\fP, \f5nonlinear-virtual\fP),
  1274. \f2same-screen?\fP, \f2focus?\fP, \f2button-mask\fP.
  1275. .
  1276. .IP "\f3focus-in, focus-out:\fP"
  1277. .Ix "Event types" focus-in
  1278. .Ix "Event types" focus-out
  1279. \f2window\fP, \f2cross-mode\fP, \f2focus-detail\fP (one of the symbols
  1280. \f5ancestor\fP, \f5virtual\fP, \f5inferior\fP, \f5nonlinear\fP,
  1281. \f5nonlinear-virtual\fP, \f5pointer\fP, \f5pointer-root\fP, \f5none\fP).
  1282. .
  1283. .IP "\f3keymap-notify:\fP"
  1284. .Ix "Event types" keymap-notify
  1285. \f2window\fP, \f2keymap\fP (a string of length 32).
  1286. .
  1287. .IP "\f3expose:\fP"
  1288. .Ix "Event types" expose
  1289. \f2window\fP, \f2x\fP, \f2y\fP, \f2width\fP, \f2height\fP, \f2count\fP.
  1290. .
  1291. .IP "\f3graphics-expose:\fP"
  1292. .Ix "Event types" graphics-expose
  1293. \f2window\fP, \f2x\fP, \f2y\fP, \f2width\fP, \f2height\fP, \f2count\fP,
  1294. \f2major-code\fP, \f2minor-code\fP.
  1295. .
  1296. .IP "\f3no-expose:\fP"
  1297. .Ix "Event types" no-expose
  1298. \f2window\fP, \f2major-code\fP, \f2minor-code\fP.
  1299. .
  1300. .IP "\f3visibility-notify:\fP"
  1301. .Ix "Event types" visibility-notify
  1302. \f2window\fP, \f2visibility-state\fP (one of the symbols \f5unobscured\fP,
  1303. \f5partially-obscured\fP, \f5fully-obscured\fP).
  1304. .
  1305. .IP "\f3create-notify:\fP"
  1306. .Ix "Event types" create-notify
  1307. \f2parent-window\fP, \f2window\fP, \f2x\fP, \f2y\fP, \f2width\fP, \f2height\fP,
  1308. \f2border-width\fP, \f2override-redirect?\fP.
  1309. .
  1310. .IP "\f3destroy-notify:\fP"
  1311. .Ix "Event types" destroy-notify
  1312. \f2event-window\fP, \f2window\fP.
  1313. .
  1314. .IP "\f3unmap-notify:\fP"
  1315. .Ix "Event types" unmap-notify
  1316. \f2event-window\fP, \f2window\fP, \f2from-configure\fP.
  1317. .
  1318. .IP "\f3map-notify:\fP"
  1319. .Ix "Event types" map-notify
  1320. \f2event-window\fP, \f2window\fP, \f2override-redirect\fP.
  1321. .
  1322. .IP "\f3map-request:\fP"
  1323. .Ix "Event types" map-request
  1324. \f2parent-window\fP, \f2window\fP.
  1325. .
  1326. .IP "\f3reparent-notify:\fP"
  1327. .Ix "Event types" reparent-notify
  1328. \f2event-window\fP, \f2parent-window\fP, \f2window\fP, \f2x\fP, \f2y\fP,
  1329. \f2override-redirect\fP.
  1330. .
  1331. .IP "\f3configure-notify:\fP"
  1332. .Ix "Event types" configure-notify
  1333. \f2event-window\fP, \f2window\fP, \f2x\fP, \f2y\fP, \f2width\fP,
  1334. \f2height\fP, \f2border-width\fP, \f2above-window\fP,
  1335. \f2override-redirect?\fP.
  1336. .
  1337. .IP "\f3configure-request:\fP"
  1338. .Ix "Event types" configure-request
  1339. \f2parent-window\fP, \f2window\fP, \f2x\fP, \f2y\fP, \f2width\fP, \f2height\fP,
  1340. \f2border-width\fP, \f2above-window\fP, \f2stack-mode\fP (see
  1341. \f2set-window-stack-mode!\fP above), \f2value-mask\fP (an integer).
  1342. .
  1343. .IP "\f3gravity-notify:\fP"
  1344. .Ix "Event types" gravity-notify
  1345. \f2event-window\fP, \f2window\fP, \f2x\fP, \f2y\fP.
  1346. .
  1347. .IP "\f3resize-request:\fP"
  1348. .Ix "Event types" resize-request
  1349. \f2window\fP, \f2width\fP, \f2height\fP.
  1350. .
  1351. .IP "\f3circulate-notify:\fP"
  1352. .Ix "Event types" circulate-notify
  1353. \f2event-window\fP, \f2window\fP, \f2place\fP.
  1354. .
  1355. .IP "\f3circulate-request:\fP"
  1356. .Ix "Event types" circulate-request
  1357. \f2parent-window\fP, \f2window\fP, \f2place\fP.
  1358. .
  1359. .IP "\f3property-notify:\fP"
  1360. .Ix "Event types" property-notify
  1361. \f2window\fP, \f2atom\fP, \f2time\fP, \f2property-state\fP (one of the
  1362. symbols \f5new-value\fP, \f5deleted\fP).
  1363. .
  1364. .IP "\f3selection-clear:\fP"
  1365. .Ix "Event types" selection-clear
  1366. \f2window\fP, \f2selection-atom\fP, \f2time\fP.
  1367. .
  1368. .IP "\f3selection-request:\fP"
  1369. .Ix "Event types" selection-request
  1370. \f2owner-window\fP, \f2requestor-window\fP, \f2selection-atom\fP,
  1371. \f2target-atom\fP, \f2property-atom\fP, \f2time\fP.
  1372. .
  1373. .IP "\f3selection-notify:\fP"
  1374. .Ix "Event types" selection-notify
  1375. \f2requestor-window\fP, \f2selection-atom\fP, \f2target-atom\fP,
  1376. \f2property-atom\fP, \f2time\fP.
  1377. .
  1378. .IP "\f3colormap-notify:\fP"
  1379. .Ix "Event types" colormap-notify
  1380. \f2window\fP, \f2colormap\fP, \f2new?\fP, \f2colormap-installed?\fP.
  1381. .
  1382. .IP "\f3client-message:\fP"
  1383. .Ix "Event types" client-message
  1384. \f2window\fP, \f2message type\fP (an atom), \f2message data\fP
  1385. (a string of length 20, or a vector of 10 or 5 integer numbers,
  1386. or, if the format field of the event is wrong, the format as a
  1387. number).
  1388. .
  1389. .IP "\f3mapping-notify:\fP"
  1390. .Ix "Event types" mapping-notify
  1391. \f2window\fP, \f2request\fP (one of the symbols \f5modifier\fP,
  1392. \f5keyboard\fP, \f5pointer\fP), \f2keycode\fP, \f2count\fP.
  1393. .
  1394. .Ch Inter-Client Communication Functions
  1395. .
  1396. .Pr iconify-window window screen-number
  1397. See \f2XIconifyWindow\fP.
  1398. .
  1399. .Pr withdraw-window window screen-number
  1400. See \f2XWithdrawWindow\fP.
  1401. .
  1402. .Pr reconfigure-wm-window . args
  1403. See \f2XReconfigureWMWindow\fP.
  1404. .LP
  1405. For the format of the arguments see \f2create-window\fP
  1406. .Ix create-window
  1407. above.
  1408. Mandatory attributes are \f2window\fP and \f2screen-number\fP
  1409. (an integer).
  1410. Optional attributes are \f2x\fP, \f2y\fP, \f2width\fP, \f2height\fP
  1411. \f2border-width\fP (integers), \f2sibling\fP (a window), and
  1412. \f2stack-mode\fP (a symbol; one of \f5above\fP, \f5below\fP, \f5top-if\fP,
  1413. \f5bottom-if\fP, \f5opposite\fP).
  1414. .
  1415. .Pr get-text-property window atom
  1416. See \f2XGetTextProperty\fP.
  1417. Returns a text property as a list of strings or #f if the specified property
  1418. does not exist.
  1419. .
  1420. .Pr set-text-property! window value atom
  1421. See \f2XSetTextProperty\fP.
  1422. \f2value\fP is a list holding the items of the text property
  1423. (strings or symbols).
  1424. .
  1425. .Pr wm-protocols window
  1426. See \f2XGetWMProtocols\fP.
  1427. Returns a vector of atoms.
  1428. .
  1429. .Pr set-wm-protocols! window protocols
  1430. See \f2XSetWMProtocols\fP.
  1431. \f2protocols\fP is a vector of atoms.
  1432. .
  1433. .Pr wm-name window
  1434. See \f2XGetTextProperty\fP.
  1435. Returns the WM_NAME property as a list of strings or #f if it does not exist.
  1436. .
  1437. .Pr set-wm-name! window name
  1438. See \f2XSetTextProperty\fP.
  1439. \f2name\fP is a list of strings or symbols.
  1440. .
  1441. .Pr wm-icon-name window
  1442. See \f2XGetTextProperty\fP.
  1443. Returns the WM_ICON_NAME property as a list of strings
  1444. or #f if it does not exist.
  1445. .
  1446. .Pr set-wm-icon-name! window name
  1447. See \f2XSetTextProperty\fP.
  1448. \f2name\fP is a list of strings or symbols.
  1449. .
  1450. .Pr wm-client-machine window
  1451. See \f2XGetTextProperty\fP, \f2XGetWMClientMachine\fP.
  1452. Returns the WM_CLIENT_MACHINE property as a list of strings
  1453. or #f if it does not exist.
  1454. .
  1455. .Pr set-wm-client-machine! window value
  1456. See \f2XSetTextProperty\fP, \f2XSetWMClientMachine\fP.
  1457. \f2value\fP is a list of strings or symbols.
  1458. .
  1459. .Pr wm-class window
  1460. See \f2XGetClassHint\fP.
  1461. Returns a pair (name and class) each component of which is either
  1462. a string or #f.
  1463. .
  1464. .Pr set-wm-class! window name class
  1465. See\f2 XSetClassHint\fP.
  1466. \f2name\fP and \f2class\fP are strings or symbols.
  1467. .
  1468. .Pr wm-command window
  1469. See \f2XGetCommand\fP (in X11 Release 4 or newer releases).
  1470. Returns the value of the WM_COMMAND property of the given window
  1471. as a list of strings.
  1472. .
  1473. .Pr set-wm-command! window command
  1474. See \f2XSetCommand\fP.
  1475. \f2command\fP is a list; each element is either a string or a symbol.
  1476. .
  1477. .Pr transient-for window
  1478. See \f2XGetTransientForHint\fP.
  1479. Returns a window.
  1480. .
  1481. .Pr set-transient-for! window property-window
  1482. See \f2XSetTransientForHint\fP.
  1483. .
  1484. .Pr wm-normal-hints window
  1485. See \f2XGetWMSizeHints\fP.
  1486. Returns a list of hints.
  1487. Each element is set to the empty list if the corresponding hint
  1488. has not been set for the specified window.
  1489. .LP
  1490. The elements of the list correspond to the following hints
  1491. (in this order): \f2x\fP, \f2y\fP, \f2width\fP, and \f2height\fP
  1492. (program specified); \f2x\fP, \f2y\fP, \f2width\fP and \f2height\fP
  1493. (user specified); \f2min-width\fP and \f2min-height\fP; \f2max-width\fP
  1494. and \f2max-height\fP; \f2width-inc\fP and \f2height-inc\fP;
  1495. \f2min-aspect-x\fP, \f2min-aspect-y\fP, \f2max-aspect-x\fP and
  1496. \f2max-aspect-y\fP; \f2base-width\fP and \f2base-height\fP;
  1497. and \f2gravity\fP.
  1498. All elements are integers except for the value of \f2gravity\fP
  1499. which is a symbol (see the \f2window-gravity\fP
  1500. .Ix window-gravity
  1501. procedure above).
  1502. .
  1503. .Pr set-wm-normal-hints! . args
  1504. See \f2XSetWMSizeHints\fP.
  1505. For the format of the arguments see \f2create-window\fP
  1506. .Ix create-window
  1507. above.
  1508. Attributes are \f2window\fP (mandatory) and the names of the hints
  1509. listed under \f2wm-normal-hints\fP
  1510. .Ix wm-normal-hints
  1511. above.
  1512. .
  1513. .Pr wm-hints window
  1514. See \f2XGetWMHints\fP.
  1515. Returns a list of hints.
  1516. Each element is set to the empty list if the corresponding hint
  1517. has not been set for the specified window.
  1518. .LP
  1519. The elements of the list correspond to the following hints
  1520. (in this order): \f2input?\fP, \f2initial-state\fP, \f2icon-pixmap\fP,
  1521. \f2icon-window\fP, \f2icon-x\fP, \f2icon-y\fP, \f2icon-mask\fP,
  1522. and \f2window-group\fP.
  1523. The value of \f2input?\fP is a boolean.
  1524. \f2initial-state\fP is a symbol (\f5dont-care\fP, \f5normal\fP, \f5zoom\fP,
  1525. \f5iconic\fP, \f5inactive\fP).
  1526. The values of \f2icon-pixmap\fP and \f2icon-mask\fP are pixmaps.
  1527. \f2icon-window\fP and \f2window-group\fP are windows.
  1528. \f2icon-x\fP and \f2icon-y\fP are integers.
  1529. .
  1530. .Pr set-wm-hints! . args
  1531. See \f2XSetWMHints\fP.
  1532. For the format of the arguments see \f2create-window\fP
  1533. .Ix create-window
  1534. above.
  1535. Attributes are \f2window\fP (mandatory) and the names of the hints
  1536. listed under \f2wm-hints\fP
  1537. .Ix wm-hints
  1538. above.
  1539. .
  1540. .Pr icon-sizes window
  1541. See \f2XGetIconSizes\fP.
  1542. Returns a vector of lists of six integers (\f2min-width\fP, \f2min-height\fP,
  1543. \f2max-width\fP, \f2max-height\fP, \f2width-inc\fP, and \f2height-inc\fP).
  1544. .
  1545. .Pr set-icon-sizes! window icon-sizes
  1546. See \f2XSetIconSizes\fP.
  1547. \f2icon-sizes\fP is a vector of lists of six integers (see \f2icon-sizes\fP
  1548. .Ix icon-sizes
  1549. above).
  1550. .
  1551. .Ch Keyboard Utility Functions
  1552. .
  1553. .Pr display-min-keycode display
  1554. .Up
  1555. .Pr display-max-keycode display
  1556. Returns the minimum/maximum keycode (an integer) for the given display.
  1557. .
  1558. .Pr display-keysyms-per-keycode display
  1559. Returns the number of keysyms per keycode for the given display.
  1560. .
  1561. .Pr string\(mi>keysym string
  1562. See \f2XStringToKeysym\fP.
  1563. \f2string\fP is a string or a symbol.
  1564. Returns an integer if \f2XStringToKeysym\fP succeeds, #f otherwise.
  1565. .
  1566. .Pr keysym\(mi>string keysym
  1567. See \f2XKeysymToString\fP.
  1568. \f2keysym\fP is an integer.
  1569. Returns #f if \f2XKeysymToString\fP fails.
  1570. .
  1571. .Pr keycode\(mi>keysym display keycode index
  1572. See \f2XKeycodeToKeysym\fP.
  1573. \f2keycode\fP and \f2index\fP are integers.
  1574. .
  1575. .Pr keysym\(mi>keycode display keysym
  1576. See \f2XKeysymToKeycode\fP.
  1577. \f2keysym\fP is an integer.
  1578. .
  1579. .Pr lookup-string display keycode mask
  1580. See \f2XLookupString\fP.
  1581. \f2keycode\fP is an integer.
  1582. \f2mask\fP is a list of symbols (\f5shift\fP, \f5lock\fP, \f5control\fP,
  1583. \f5mod1\fP .. \f5mod5\fP, \f5button1\fP .. \f5button5\fP,
  1584. or \f5any-modifier\fP).
  1585. .
  1586. .Pr rebind-keysym display keysym modifiers string
  1587. See \f2XRebindKeysym\fP.
  1588. \f2keysym\fP is an integer.
  1589. \f2modifiers\fP is a vector of integers.
  1590. .
  1591. .Pr refresh-keyboard-mapping window type
  1592. See \f2XRefreshKeyboardMapping\fP.
  1593. \f2type\fP is a symbol (\f5modifier\fP, \f5keyboard\fP, or \f5pointer\fP).
  1594. Invokes \f2XRefreshKeyboardMapping\fP with a faked event structure holding
  1595. the specified window and request type.
  1596. .
  1597. .Ch Other Utility Functions
  1598. .
  1599. .Pr xlib-release-4-or-later?
  1600. Returns always #t.
  1601. .
  1602. .Pr xlib-release-5-or-later?
  1603. Returns #t iff the Xlib extension is linked together with the X11
  1604. Release 5 Xlib or later versions of the Xlib.
  1605. .
  1606. .Pr get-default display program option
  1607. See \f2XGetDefault\fP.
  1608. \f2program\fP and \f2option\fP are strings or symbols.
  1609. Returns a string of #f if the option does not exist for the
  1610. specified program.
  1611. .
  1612. .Pr resource-manager-string display
  1613. See \f2XResourceManagerString\fP.
  1614. Returns a string or #f if the RESOURCE_MANAGER property does not
  1615. exist on the root window.
  1616. .
  1617. .Pr parse-geometry string
  1618. See \f2XParseGeometry\fP.
  1619. Returns a list of six elements: two booleans indicating whether x or
  1620. or y are negative and four integers (x, y, width, and height).
  1621. Each of the elements can be #f to indicate that the respective
  1622. value was not found in the string.
  1623. .
  1624. .Pr parse-color colormap string
  1625. See \f2XParseColor\fP.
  1626. Returns an object of type \f2color\fP or #f if \f2XParseColor\fP fails.
  1627. .
  1628. .Pr store-buffer display bytes buffer
  1629. See \f2XStoreBuffer\fP.
  1630. \f2bytes\fP is a string; \f2buffer\fP is an integer between 0 and 7.
  1631. .
  1632. .Pr store-bytes display bytes
  1633. See \f2XStoreBytes\fP.
  1634. \f2bytes\fP is a string.
  1635. .
  1636. .Pr fetch-buffer display buffer
  1637. See \f2XFetchBuffer\fP.
  1638. \f2buffer\fP is an integer between 0 and 7.
  1639. Returns a string.
  1640. .
  1641. .Pr fetch-bytes display
  1642. See \f2XFetchBytes\fP.
  1643. Returns a string.
  1644. .
  1645. .Pr rotate-buffers display delta
  1646. See \f2XRotateBuffers\fP.
  1647. \f2delta\fP is an integer (the amount to rotate the buffers).
  1648. .
  1649. .Sy with object . body-forms
  1650. \f2object\fP must be a drawable, a graphics context, or a font.
  1651. The \f2body-forms\fP are evaluated in order; \f2with\fP returns the value
  1652. of the last body-form.
  1653. .LP
  1654. Within the scope of the \f2with\fP, the first call to an accessor
  1655. function accessing \f2object\fP (such as \f5window-\fP\f2attribute\fP
  1656. or \f5font-\fP\f2attribute\fP) causes the result of the corresponding
  1657. Xlib function to be retained in a cache; subsequent calls just return
  1658. the value from the cache.
  1659. Likewise, calls to Xlib functions for mutator functions modifying
  1660. \f2object\fP (such as \f5set-window-\fP\f2attribute\fP\f5!\fP)
  1661. are delayed until exit of the \f2with\fP body or until an accessor
  1662. function is called and the cached data for this accessor function
  1663. has been invalidated by the call to a mutator function.
  1664. .
  1665. .Ch Server Extension Functions
  1666. .
  1667. .Pr list-extensions display
  1668. See \f2XListExtensions\fP.
  1669. Returns a vector of strings.
  1670. .
  1671. .Pr query-extension display name
  1672. See \f2XQueryExtension\fP.
  1673. \f2name\fP is a string or a symbol.
  1674. Returns a list of three elements: the major opcode (an integer) or #f
  1675. if the extension has no major opcode, the base event type code (an
  1676. integer) of #f if the extension has no additional event types, and
  1677. the base error code (an integer) of #f if the extension has no
  1678. additional error codes.
  1679. \f2query-extension\fP returns #f if the specified extension is not present.
  1680. .
  1681. .Ch Error Handling
  1682. .
  1683. .Va x-error-handler
  1684. See \f2XSetErrorHandler\fP.
  1685. If an error event is received and the global variable \f2x-error-handler\fP
  1686. is bound to a compound procedure, this procedure is invoked with the
  1687. following arguments: a display, the serial number of the failed request
  1688. (an integer), the error code (either an integer or one of the symbols
  1689. \f5bad-request\fP, \f5bad-value\fP, \f5bad-window\fP, \f5bad-pixmap\fP, 
  1690. \f5bad-atom\fP, \f5bad-cursor\fP, \f5bad-font\fP, \f5bad-match\fP, 
  1691. \f5bad-drawable\fP, \f5bad-access\fP, \f5bad-alloc\fP, \f5bad-color\fP, 
  1692. \f5bad-gcontext\fP, \f5bad-id-choice\fP, \f5bad-name\fP, \f5bad-length\fP, 
  1693. or \f5bad-implementation\fP), the major and minor op-code of the
  1694. failed request (integers), and a resource-ID (an integer).
  1695. .LP
  1696. If an error event is received and this variable is not bound to a
  1697. compound procedure, the Xlib default error handler is invoked.
  1698. The initial value of this variable is the empty list.
  1699. .
  1700. .Va x-fatal-error-handler
  1701. See \f2XSetIOErrorHandler\fP.
  1702. If a fatal I/O error occurs and the global variable
  1703. \f2x-fatal-error-handler\fP is bound to a compound procedure, this
  1704. procedure is invoked with a display as argument.
  1705. The procedure must invoke \f2exit\fP.
  1706. If a fatal error occurs and this variable is not bound to a
  1707. compound procedure, or if the procedure returns, the Xlib default
  1708. fatal error handler is invoked and the interpreter terminates with
  1709. an exit code of 1.
  1710. The initial value of this variable is the empty list.
  1711. .
  1712. .Ch Interaction with the Garbage Collector
  1713. .
  1714. .PP
  1715. .Ix "garbage collector"
  1716. The Scheme garbage collector destroys objects of type \f2colormap\fP,
  1717. \f2cursor\fP, \f2display\fP, \f2font\fP, \f2gcontext\fP, \f2pixmap\fP,
  1718. or \f2window\fP that are not longer accessible from within the Scheme
  1719. program.
  1720. This is done by invoking the function \f2free-colormap\fP, \f2free-cursor\fP,
  1721. \f2close-display\fP, \f2close-font\fP, \f2free-gcontext\fP,
  1722. \f2free-pixmap\fP, or \f2destroy-window\fP, respectively, with the
  1723. object to be destroyed as an argument.
  1724. .PP
  1725. The garbage collector only destroys objects that have been created
  1726. from with the Scheme program (by functions like \f2create-pixmap\fP
  1727. or \f2open-display\fP).
  1728. Objects that have been obtained from the Xlib through functions like
  1729. \f2display-default-colormap\fP (and are owned by the Xlib internals),
  1730. are ignored by the garbage collector.
  1731. .PP
  1732. Programmers must make sure that an object is accessible during the object's
  1733. entire lifetime, otherwise future runs of the garbage collector can
  1734. result in undesired termination of the object.
  1735. One must be especially careful when results of functions that create
  1736. new objects (such as \f2create-window\fP) are ignored or assigned
  1737. to local variables as in
  1738. .Ss
  1739. (define dpy (open-display))
  1740. (define root (display-root-window dpy))
  1741. .sp .5
  1742. (do ((x 0 (+ x 10)) (y 0 (+ y 10))) ((= x 50))
  1743.   (let ((win
  1744.           (create-window 'parent root 'x x 'y y 'width 20 'height 20)))
  1745.     (manage-window win)))
  1746. .Se
  1747. .PP
  1748. In this example, after termination of the do-loop, the garbage
  1749. collector will destroy the newly created windows, as they are not
  1750. accessible from within the program.
  1751. If this is not desired, the windows could be put into a variable (for
  1752. instance, be \f2consed\fP into a list) that is defined outside of the
  1753. body of the loop.
  1754.